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-Introduction— ~~~ ~- 

Many applications, especially server applications, are increasing in complexity, often to 
the point where they are difficult to understand and to manage. To aid In analyzing 

complex applications, the Windows NT® Performance Monitor provides a general, customizable mechanism to view 
various counters and other metrics within a running application. This article describes a set of COM Interfaces, C++ 
code, and utility components that make It easy for the developer to add customized counters to Performance Monitor. 
This article begins by briefly describing the complexities of the native Performance Monitor interface, introduces some 
new COM Interfaces, macros and utilities, and finally leads the reader through an example where we add several 
counters to a program. 



The Benefits of Instrumenting Your Application 

There are two primary benefits to using Performance Monitor to instrument an application. First, Performance Monitor 
can be used to tune an application. Second, a developer can use custom performance monitor counters to diagnose 
problems, thereby producing a higher quality application. 

Performance Monitor displays data in terms of objects and counters. Objects included with Windows NT include Process 
and Memory. Counters for the Process object include the number of running threads and the process's CPU utilization. 
An application integrates with Performance Monitor by providing objects and counters that are specific to the application. 
Because the counters are application-specific, they can be used to monitor virtually any aspect of a running application. 
A common use of custom performance monitor counters is to track the amount of resources used by an application. 
Information gathered through the custom counters can then be used to tune the application. For example, counters can 
be used to monitor the number of users contending for a shared resource within the application. By viewing the counter 
data using Performance Monitor, a developer can determine when access to the shared resource becomes a bottleneck in 
the application. At this point, the developer may choose to expand the number of resources available to the connected 
users. 

Custom Performance Monitor counters can also used to aid in debugging. Counters can be used to track conditions in the 
application without having to run the application under a debugger or add case-specific tracking code. For example, a 
common problem encountered when developing COM applications is object reference counting. Too many reference 
counts results in a COM object staying in memory longer than it should while too few reference counts results in objects 
being destroyed prematurely. Custom counters can be used to diagnose these situations. Counters can be added that 
track outstanding object references within a COM server. By watching the reference counts through Performance 
Monitor, a developer can identify portions of the application that include reference counting problems. 

Using Performance Monitor as an additional tuning and debugging tool helps you build better quality applications. As a 
result, these applications will have a substantially lower total cost of ownership (TCO) in the long run. 

Custom counter example 

Microsoft® SQL Server^^ Is an excellent example of an application that makes extensive use of custom Performance 
Monitor counters. SQL Server provides several objects and counters that can be used by administrators and developers 
to tune the server. For example, counters can be used to determine the number and types of locks held on tables, the 
number of connections to the server, and the effectiveness of the procedure cache. Figure 1 shows some of the counters 
for the SQLServer-Locks object. 
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Figure 1. 



Adding Custom Performance Monitor Counters 

The Windows NT Performance Monitor provides facilities that allow applications to add custom performance counters. 
Performance Monitor displays these counters in the same way that it displays the counters provided by the operating 
system. 

Much of the work required to implement custom counters is the same for all applications. This article describes a set of 
COM interfaces, C++ classes, and utility components that provide the code that is common to all applications. This 
leaves the developer to concentrate on counter design and on the specifics of gathering the counter data. 

Adding custom counters requires several steps. This section describes those steps, provides a brief overview of the 
performance monitor interface, and then describes the framework weVe developed for making the process of adding 
custom counters easier. 

The Native Performance Monitor Interface 

When adding custom performance monitor counters, a developer must first determine what aspects of the application to 
measure. For example, a multiuser NT Server application may want to monitor how many users are connected to the 
application. After the counters are designed, the following steps must be followed to display the counters using 
performance monitor: 

1. Add the required registry entries. 

2. Implement a Performance DLL. 

3. Develop a means for the Performance DLL and the application to communicate. 

4. Modify the application to collect the data. 

These steps are described In detail in the following sections. Figure 2 shows the architecture of Performance Monitor with 
respect to custom application counters. 
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Figure 2. 

Required Registry Entries 

Performance Monitor uses the registry to determine which appiicatlons provide custom counters. Those applications that 
provide custom counters include a Performance key under their application key. Figure 3 shows the Performance key for 
Microsoft SQL Server. This key is located in HKEY.LOCAL_MACHINE\SYSTEM\CurrentControiSet\Services\MSSQLServer. 
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Figure 3. 

The names and descriptions of each application's custom counters are also stored in the registry. The list of ail available 
counters is found under HKEY_LOCAL_MACHINE\SOFTWARE\Mlcrosoft\Windows NT\CurrentVerslon\Perflib. Performance 
nnonitor uses this information to display a list of available counters in Its user Interface. Developers use a tool called 
lodctr to add counter names and descriptions to the registry. The Input to lodctr is an .ini nie that provides the name 
and help text for each custom counter supported by the application. A sample .ini nie is provided in Figure 4. 
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[info] 

drivername-FINSERVER 

symbol file=FinPerf . h 

(languages] 

009«English 

{text] 

FlNSERVEROBJ_009_NAME=FinancialServer 
FINSERVEROBJ~009~HELP«The top level FinServer object. 
ACTIVESESSIONS_009_NAME»Active Users 

ACTIVESESSIONS~009~HELP-The number of active users connected to the server. 

— MODULEL0GKS-0a9-NAME=Module-tocks: = ^ 

MODULELOCKS_009_HELP='The number of DCOM object locks in the FinServer. 
OPENDBCONNECTS_009_NAME=Open ODBC connections 

OPENDBCONNECTs"009~HELP=The number of open ODBC connections in the FinServer. 
Figure 4. 

In addition to the entries made, lodctr also edits the application's Perfomnance key to add values used by the 
Performance DLL during the collection process. 

Implementing a Performance DLL 

Each application that supplies custom counters must provide a Performance DLL. Performance Monitor calls exported 
functions of this DLL during the data collection process. The name and location of this DLL are kept In the registry under 
the application's Performance key (Figure 3). 

Each Performance DLL must export three functions. These functions are called to initialize the Performance DLL, collect 
counter values from it, and perform cleanup tasks before unloading it. The names of these functions can vary and are 
specified In the Open, Close, and Collect values under the application's Performance key in the registry (Rgure 3). 

Open 

The Open function is called when the user selects "Add to Chart" from the "Edit" menu (or selects the + sign on the 
toolbar) in Performance Monitor. The primary purpose of the Open function Is to give the Performance DLL a chance to 
perform initialization tasks before the data collection process begins. 

Typical tasks that are performed in the Open function include establishing a communication mechanism with the 
application being monitored, reading counter indexes from the registry, and initializing the data structures that will be 
used in the collection process. 

Collect 

The Collect function is called each time Performance Monitor needs to obtain updated counter values. A Performance 
DLL returns counter values to Performance Monitor by initializing a number of data structures that define the 
characteristics of the counters and their current values. These structures are placed in memory supplied by Performance 
Monitor. The structures used in the collection process are defined in the winperf.h header file. The layout of these 
structures in memory Is shown in Figure 5. The primary data structures from winperf.h are described briefly below. 
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Figure 5, 
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PERF_OBJECT_TYPE 

This structure defines a Performance Monitor object Examples of objects supplied by Windows NT are Processor, 
Memory, and Cache. 

PERF.COUNTER.DEFINITION 

The characteristics of a custom counter are specified in the PERF_COUNTER_DEFII\irriON structure. Information in this 
structure includes the data type of the counter, its size, and its default scale. 

~P€RF-GOUNTER-BUOCK — — 

The PERF_COUNTER„BLOCK structure marks the beginning of the actual counter values. The only field In this structure Is 
a size field that specifies the amount of memory taken up by all of the counter values. 

Close 

The Close function Is called when Performance Monitor exits. The Close function gives the Performance DLL a chance to 
perform cleanup tasks. These typically include closing the communication mechanism with the application and freeing 
any data structures allocated during the collection process. 

Communicating with the application 

Because the Performance DLL is loaded in the Performance Monitor address space, an Inter-process communication 
mechanism must be established between the Performance DLL and the application being monitored. Typically the 
communication mechanism is initialized In the Performance DLL's Open function and used in the Collect function to 
retrieve the counter values from the application. 

Any of the available Win32 inter-process communication mechanisms can be used. These include memory-mapped files, 
named pipes, and COM interface calls. Performance Monitor does not define a standarxJ communication mechanism 
between Performance DLLs and applications. It is up to the developer to Implement a communication scheme for each 
application that supports custom counters. 

Collecting the performance data 

The final step in Implementing custom performance counters is to collect the performance data itself. The application 
must keep track of the data values for each of its counters and give the values to the Performance DLL on demand. The 
method used to transfer the values depends on the communication mechanism chosen In the previous step. 

Using COM Interfaces to Implement Custom Application Counters 

As can be seen from the previous section, adding custom performance monitor counters to an application is a complex 
process. In addition, much of the code required to add the counters is the same for all applications. The components 
described in this article make it significantly easier to add custom performance monitor counters to an application. 

Much of the code that is common to ail applications is supplied in a generic Performance DLL and a registration 
component. COM interfaces have been designed that provide a higher level interface than the native Performance 
Monitor API. Instead of calling the Performance Monitor API directly, the developer implements a set of components that 
support the COM interfaces described In this article. The required registry entries are made by calling a registration 
component during application initialization. The developer is left to concentrate on counter design and on the specifics of 
gathering the counter data. 

This section describes how these components are used and how they fit Into the Performance Monitor architecture (see 
Figure 6). 
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Figure 6. 



Custom Counter COM Interfaces 

This section describes the COM interfaces that have been designed to provide a higher level interface than the native 
Perfornnance Monitor API. These interfaces are IPerfmonObject ^nd IPerfmonCounten Any application that supports 
custom counters must supply a set of components that Implement these interfaces. The generic Performance DLL 
ExtCounters (described below) calls these interfaces during the data collection process and the registration component 
RegPerfCounters (described below) calls these interfaces during registration. 

There are several advantages to using these Interfaces, First, when using these interfaces, the developer does not need 
to be concerned with the details of the Performance Monitor API. These details include laying out the performance 
monitor structures In memory and defining a communication mechanism between the Performance DLL and the 
application. Second, because the generic Performance DLL communicates with the application through COM Interfaces, 
the components used to collect the pert^ormance data can be written In any language. This approach makes It easier for 
applications written In languages like Visual Basic® to support custom peil'ormance monitor counters. 

The IPerfmonObJect interface represents a performance monitor object. Examples of performance monitor objects 
included with NT are Process and Thread. SQL Server adds custom objects Including SQL Sen/er-Procedure Cache and 
SQL Server-Log. In the approach presented in this document, each application exposes a Performance Monitor object. 

The IPerfmonCounter interface represents a custom pert^ormance monitor counter. These counters hold the data values 
being monitored within the application. Examples of counters from the NT Process object include Thread Count and 
Handle Count. A Performance Monitor object can have any number of counters. 

We have also provided a set of C++ classes and macros to make It easy to build components that expose the interfaces 
described above. The classes IPerfmonObJectlmpt and IPerfmonCounterlmpt provide default Implementations for each 
member of IPerformObject and IPerfmonCounter. These classes are described later in the document. 

The following sections provide explanations for each member of IPerfmonObject and IPerfmonCounter. As described 
above, the default Implementations provide by IPerfmonObJectlmpi and IPerfmonCounterJmpi are generally sufficient. 

IPerfM nObJect 

Each application Implements one component that exposes this interface. This component Is referred to as the 
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application's collection component throughout this document. The collection component represents the application's 
performance monitor object. This Interface provides the top-level connection to the Performance DLL The definition of 
IPerfmonObJect Is: 



interface IPerfmonObject : IDispatch 
{ 

HRESULT GetName([out, retval] BSTR *pName); 
HRESULT GetHelp{ tout, retval] BSTR *pHelp) ; 
HRESULT Getlndex( tout, retval] long *pindex) ; 
HRESULT GetNumCounters ( (out, retval] long *pNuraCounters) ; 
HRESULT GetCounters ( [ out, retval ] lUnknown **pronnf pr?) ; 



Figure 7. 



GetName 

Returns the name of the Performance Monitor object. This name is added to the list of Performance Monitor objects in 
the registry during the registration process. The name Is then displayed in the "Object" dropdown on the "Add To Chart- 
dialog box In the Performance Monitor user interface (Figure 8). 



GetHelp 

Returns the help text for the Performance Monitor object. Like the name, an object's help text is entered in the registry 
and displayed in the Performance Monitor user interface. The help text is shown when the user chooses the "Explain" 
button in the "Add To Chart" dialog (Figure 8). 




Figure 8. 



Getlndex 

Performance Monitor requires that each object and counter be Identified by a unique index. This index is stored in the 
registry along with the object's name and help text. Index values are always even numbers. This method returns the 
index for the application's Performance Monitor object. 

GetNumCounters 

Returns the number of custom counters for this object. 
GetC unters 

This method returns a COM enumeration containing IPerfmonCounter Interface pointers to each of the object's counters. 
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IPerfmonCounter 

An application impiements one component that exposes this interface for each custom counter it provides. 

Both the ExtCounters DLL and the registration component use these interfaces to gather information about a custom 
counter. The definition of IPerfmonCounter \s: 

interface ZPerfmonCounter : IDispatch 
{ 

HRESULT GetName( [out, retval] BSTR ♦pName] ; 
HRESULT GetHelp( (out, retval J BSTR *pHelp] ; 

HRESULT Getlnd ex( fout r&.tvaXl-long-*pIndex-U; ■. 

HRESULT GetDataType( (out, retval] short *pDataType); 
HRESULT Collect ([out, retval] VARIANT *pVariant); 

); 

Figure 9. 
GetName 

Returns the name of the custom counter. As with Performance i^onitor objects, the name of each counter is stored in the 
registry and displayed in the Performance Monitor user interface. The "Counter" ilst box on the "Add To Chart" dialog 
lists the custom counters for the selert object (Figure 7). 

GetHelp 

Returns the counter's help text. The help text is stored in the registry and displayed in the Performance Monitor user 
interface when a user chooses the "Explain" button (Rgure 7). 

Getlndex 

Returns the counter's unique index. 
GetDataType 

This member returns the data type of the counter. Data types are identified using the values from the VARTYPE 
enumeration used in OLE Automation. For example, if the counter is a 4-byte integer, this member would return VT_I4. 

Collect 

This member Is called by the Performance DLL to collect the latest value for the custom counter. The return type of this 
member is VARIANT. VARIANTS are used to provide flexibility in the type of data that can be returned. The 
implementation of Collect is responsible for correctly initializing the VARIANT with the appropriate type and data values. 
The Performance DLL will look at the type of data in the VARIANT and extract the data before passing it onto 
Performance Monitor. 

C++ Support 

We have provided two C++ classes that make it easy to implement IPerfmonObject and IPerfmonCounter. The class 
IPerfmonObjectlmpt provides an implementation of IPerfmonObject and IPerfmonCounterlmpl provides an 
implementation of IPerfmonCounter. The goal in providing these classes Is to minimize the amount of coding required to 
add custom performance monitor counters to an application. These classes are designed to fit easily into projects that 
Implement COM components using ATL. 

IPerfmonObjectlmpI 

IPerfmonObJectlmpl provides a default implementation of the IPerfmonObject interface. This class fits into the ATL class 
hierarchy that is used to build COM components. IPerfmonObJectlmpl uses ATL's concept of a map to allow developers to 
easily specify the custom counters for their application. Typically, a developer will derive a class from 
IPerfmonObJectlmpl and specify a map that describes the custom counters. Figure 10 provides an example of a class 
derived from IPerfmonObJectlmpl. The sections of code that relate to IPerfmonObJectlmpl are shown in bold. 
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class CMySrvCounters ; 

public CComObjectRootEx<CComMultiThreaclModel>, 

public CComCoClass<CMySrvCounters, &CLSID_CMySrvCounters>, 

public IPerfaonObjectlmpK&LIBID MYSRVSBRVERLib> 

{ 

public: 

DECLARE_REGISTRY_RESOURCEID(IDR_MYSRVCOUNTERS) 
BEGIN_COM_MAP (CMySrvCounters ) 

COM_I NTERFAC E_ENTRY ( I Pe r f monOb j e C t ) 

COM INTERFACe " entry ( IDispat ch) ^ ^ , 

END_COM_MAP ( ) " 

BEGiH_C0UNTER_M2lP ( IPerfmonCounterlmpX) 
COUNTER_ENTRY_LONC<"Huinber of Users", 

"The number of users connected to the application", 

£m_n\uiiUsers) 

COUNTER_ENTRX_LONG_FUNC( "Number of ODBC Connections", 

"The number of ODBC connections the application has open" , 
GetNuz&ODBCConnections ) 

BHD COUNTER_MAP() 

); " 
Figure 10. 

This class uses a counter map to Implement two custom performance counters. The counter map works like ATI's COM 
map. Specifying the map will be very familiar to ATL programmers following ATL's style. The counter map begins and 
ends with the BEGIN_COUNTER_MAP() and END_COUNTER.MAP() entries respectively. BEGIN_COUNTER_MAP() has a 
parameter that specifies the type of object to create to represent a counter. Typically, this parameter will be 
IPerfmonCounterlmpL This is described In more detail In the following section. 

We have provided two macros for specifying the custom counters themselves. Using these macros, a developer can add 
a custom counter with very little coding. COUNTER_ENTRY_LONG() Is used to specify a counter whose latest value is 
always kept in a variable. If more flexibility Is needed, COUNTER^ENTRYaONG_FUNC() can be used to specify a 
function that can be called to retrieve the latest counter value. The developer is responsible for implementing this 
function, This function will be called each time Performance Monitor asks for the latest counter values. 

There are obviously several other macros that could be written to specify counters. These macros could include support 
for other data types and different methods of accessing counter data. 

IPerfmonCounterlmpI 

Instances of IPerfmonCounterlmpI are constructed by the application's Instance of IPerfmonObjectlmpL These Instances 
are released by the ExtCounters Performance DLL. When ExtCounters calls IPerfmonObJect::GetCounters, the 
Instance of IPerfmonObJectlmpI uses the information In the counter map to properly construct the appropriate number of 
Instances of IPerfmonCounterlmpI, 

IPerfmonCounterlmpI shouldn't have to be derived from if the developer uses the default implementation provided by 
IPerfmonObJectlmpI, However, BEGIN_COUNTER_MAP() is parameterized to allow flexibility In situations where 
developers want to use an implementation of IPerfmonCounter other than the one provided by IPerfmonCounterlmpI, 

The Registration Component 

The registration component (RegPerfCounters) is used to write all the data to the registry that is needed for an 
application to support custom performance counters. This data Includes the application's Performance key and the object 
and counter values typically done using the lodctr utility. 

Registration is done using a COM interface called IRegisterPerfmonObject that Is exposed by the RegPerfCounters 
component. This interface is described below. Because registration is done through a COM interface, the registration 
component can be called from any language, including Visual Basic. 

As mentioned previously, each application supplies one component that exposes the IPerfmonObject Interface. 
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RegPerfCounters uses this collection component to collect the data needed during registration. 

RegPerfCounters creates an InsUnce of the application's collection component and calls the GetName and GetHelp 
members of IPerfmonObJect and IPerfmonCounter when adding the counter data to the registry. 

Typically the calls to the registration component are made either during application startup or when the application is 
performing self-registration, A typical COM server will register its components when the application is started with the - 
RegServer parameter. This is an excellent opportunity to register the performance monitor counter information as well. 
Another common scenario is to register the counter information from the application's setup program. 

IReglsterPerfmonObJect 

The definition of IReglsterPerfmonObJect is: 

interface IRegisterPerfmonObject : IDispatch 
{ 

HRESULT Register { [in] BSTR appName, [inJBSTR collectionGUID) ; 
HRESULT Unregister( [injBSTR appName); 

}; 

Figure !!• 
Register 

This method registers all data needed to support custom performance monitor counters. As mentioned previously, this 
method creates an instance of the application's collection component to gather the data needed during registration. The 
parameter "collectionGUID" provides the CLSID of the application's collection component. 

UnRegister 

This method removes the application's Performance Monitor object and counter values. 
C++ utilities 

We have provided two C++ utility functions to malce it easier to call the registration component. These functions hide of 
details of creating and calling the RegPerfCounters COM component. These functions are: 

bool RegisterPerformanceCounters (LPCTSTR pAppNaroe, CLSID collectionGUID); 
bool UnRegisterPerformanceCounters (LPCTSTR pAppName); 

Figure 12. 

As their names suggest, the first function is used to register the counters and the second function is used to remove 
them from the registry. 

The ExtCounters DLL 

The ExtCounters DLL is a generic Performance DLL that can be used by any application. ExtCounters collects 
performance data from the application's collection component and formats it for use by Performance Monitor. 
ExtCounters Implements the details of interacting with Performance Monitor so the application's collection component 
can focus on collecting performance data. 

ExtCounters uses COM to communicate with the application being monitored. The use of COM as a communication 
mechanism has two advantages. First, it allows Interfaces to be defined independent of the applications being monitored. 
Second, it facilitates performance monitoring with applications written in any language that supports the creation of COM 
components. 

The ExtCounters DLL identifies an application's collection component through registry settings. When Performance 
Monitor calls the DLLs Open function, it passes the value of the Export value under the application's Linkage key. For 
the application MyServer, this key would be 
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HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MyServer\Linkage. The Export value is set to the 
application name during registration by the RegPerfCounters utility. Given the application name, ExtCounters reads the 
value of the CollectlonComponent value under the application's Performance key to find the CLSID of the collection 
component. Rgure 13 shows a Performance key with the CoilectionComponent value. 
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Figure 13. 

In the Open function, ExtCounters uses this CI-SID to create an instance of the collection component and obtain Its 
IPerfmonObJect and IPerfmonCounter interfaces. These interfaces are used to gather Information about the application's 
counters and buiid the appropriate Performance Monitor data structures. In addition, when Performance l^onitor caiis the 
Collect function in ExtCounters, the DLL calls IPerfmonCounter::Collect on each counter to retrieve the latest counter 
data. In addition to the CoilectionComponent values, several other values under the application's Performance key are 
used during the collection process (see Figure 13). These include: 

Close 

This registry value is the name of the Performance DLL's Close function. For ExtCounters, this is always 
CloseExtPerfData . 

Collect 

The Collect value holds the name of the Performance DLL's Collect function. For ExtCounters, this Is always 
CollectExtPerfData. 



First Counter, First Help, Last Counter, Last Help 

These values contain offset Information used by Performance Monitor. Indexes must be assigned for each application 
that provides custom objects and counters. An application assigns these starting at 0. These registry values represent 
the offset of a particular application's counters in Performance Monitors master list of counters. These values are written 
by the registration component described above. The registration component uses the lodctr utility to write these values. 

Library 

The Library value contains the name of the application's Performance DLL. When adding custom counters as described In 
this paper, this value will always be ExtCounters. Note that the Performance DLL must be in the path. 

Open 

This registry value is the name of the Performance DLL's Open function. For ExtCounters, this is always 
OpenExtPerfData, 



Example: Implementing Performance C unters 
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This section uses an example to illustrate how to implement performance counters In an application. Our sample 
application Is a COM server called the Financial Server. The Financial Server allows users to connect to it and perform 
various financial calculations. The Rnandal Server Is accessed via DCOM from a Visual Basic client and uses SQL Server 
as a data store. The COM components are built using ATL and data access is done through ODBC. The high-level 
architecture is shown In Figure 14. 




Figure 14. 



Step 1. Design Your Counters 

The first step in adding counters to an application Is to determine what to measure. The Rnancial Server application 
includes counters that can be used for both tuning and debugging the application. The custom counters In the Financial 
Server are: 

Active Users. This counter tracks the number of users that are currently connected to the Rnancial Server. 

ODBC Connections. This counter tracks the number of open ODBC connections in the server. 

I^odule Loclts. Because the Financial Server contains COM components, tracking the number of outstanding locks on 
the server can help debug reference counting problems. 

Queued Events. The Financial Server uses COM's connection point interfaces to send events to the Visual Basic clients. 
These events are queued in the server and sent in the order they are placed on the queue. The Queued Events counter 
tracks the number of events in the queue. 



Step 2. Add the Counters to Your Code 

After the counters have been defined, code must be added to the application to expose the IPerfmonObject and 
IPerfmonCounter interfaces. First, the IDL source for IPerfmonObject and IPerfmonCounter must be included in the 
project's IDL file. Second, the IPerfmonObjectlmpi and IPerfmonCounterlmpI classes can be used to provide 
implementations of the required interfaces. 



Include IDL source 

We have provided an IDL source file (PerfCounters.idI) that Includes the definitions of IPerfmonObject and 
IPerfmonCounter, This file must be Included In the project's IDL file as shown in Figure 15. 



// Application's interfaces described here 
// 



« include " Parf Counter s . Idl " 

// 
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// The rest of the application *3 idl source defined below 

// 

t 

uuid(DA321ED4-79EA-llD0-8A16-4000O4491007) , 
version (1.0) , 

help3tringt"FinServ 1.0 Type Library") 

] 

library FINSERVLib 
( 



); • ^ ^ 

Figure 15. 

Implement a class derived from ZPerfmonObJectlmpI 

Each application that supports custom counters must provide one COM component that implennents the IPerfmonObject 
Interface. This component is used during both the data collection process and the registration process. As described 
above, the class IPerfmonObJectlmpl makes it easy to write a component that exposes IPerfmonObject. To use 
IPerfmonObjectlmpI, a developer derives from the class and provides a counter map. See the earlier section on C++ 
support for a detailed description of IPerfmonObJectlmpL Figure 16 below shows how IPerfmonObJectlmpl is used in the 
Financial Server. 

class ATL_N0_VTABLE CFinServCounters ; 

public CComOb j ectRootEx<CCoinMultiThreadModel>, 

public CComCoClass< CFinServCounters, &CLSID_CFinServCounters>, 
public iSupportErrorlnfo, 

public I Per ffflonOb jectlo^K &LIBID_FinServLib> 

( 

public: 

CFinServCounters () i ) 

virtual - CFinServCounters () {) 
DECLARE_REGISTRY_RESOURCEID(IDR_FINSERVCOUNTERS) 
BEGIN_C0M_MAP (CFinServCounters) 

COM_INTERFACE_ENTRY ( I Pe r f monOb j ect ) 

COM_INTERFACE_ENTRY (IDispatch) 

COM~INTERFACE_ENTRY (ISupportErrorlnfo) 
END_COM_MAP() 

BE6IH_C0UNTER_MAF(IPerfmonCounterIii^l) 

COUNTER_ENTRy_LONG ( "Active Users Users", 

"The number o£ users connected to the Financial Server", 
(CFinServCounters : :m_numUser8) 
COUNTER_ENTRV_LONG_FUNC < " ODBC Connec tiona " , 

*" "The minber of ODBC connections the Financial Server has open", 
CFinServCoiinters : :GetOpenDBComiections) 
COUNTER ENTRY_LONG_FUNC ( "Module Loclcs", 

" "The n\5ber of outstanding reference counts held on the Financial Server ", 
CFinServCotinters: iGetModuleLocks) 
COUNTERJEITTRY LONG ("Queued Events", 

~ "The number of events waiting to be send fromthe Financial Server", 

^CFinServCounters : : in^queuedEvents ) 

BND_COUNTER_MAP ( ) 

// ISupportsErrorlnfo 

STDMETHOD(InterfaceSupportsErrorlnfo) (REFIID riid) / 
static long m_nuraUsers; 
static long m_queuedEvents; 

static void GetOpenDBConnections (longs numDBConnections) ; 

static void GetModuleLocIcs (long& numLoclcs); 

); 

Figure 16. 

Providing custom c unters using Visual Basic 

Both the Performance DLL (ExtCounters) and the Registration DLL ( Reg Perf Counters) communicate with the application 
through COM interfaces derived from IDispatch. As a result, the components that implement IPerfmonObject and 
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IPerfmonCounter can be written In a variety of languages including Visual Basic. Figure 17 shows a class that 
implements IPerfmonCounter in Visual Basic. 

Implements IPerfmonCounter 

Dim m_numUsers As Long 

Public Sub Class_lncrementNumUsersi) 

m_numUsers = m_numU3er3 + 1 
End Sub 

Public Sub Class_DecrementNumUsers ( ) 
m^numUsers = m^numUsers - 1 

End Sub . 

^P r i va t"e~Func tiW"I Perf monCou n t e r _Collect() As Variant 
CFinServPerfmonCounter _Collect = m_numUsers 
End Function 

Private Function IPerfmonCounter _GetDataType () As Integer 
CFinServPerfmonCounter _GetDataType = vbLong 
End Function 

Private Function IPerfmonCounter _GetHelp() As string 

CFinServPerfmonCounter _GetHelp = "The number of users connected to the Financial Server" 
End Function 

Private Function IPerfmonCounter _Getlndex() As Long 
CFinServPerfmonCounter _GetIndex = 2 
End Function 

Private Function IPerfmonCounter _GetName{) As String 
CFinServPerfmonCounter _GetName = "Active Users" 
End Function 

Figure 17. 

Step 3. Register Your Application's Counters 

As described earlier, the registration component {RegPerfCounters) is used to write all the data to the registry that is 
needed for an application to support custom performance counters. Registration is done using a COM Interface called* 
IRegisterPerfmonObJect that is exposed by the RegPerfCounters component. 

We have provided two C++ utility functions to simplify the process of calling the RegPerfCounters component. 
Registration can be done in a number of places in an application. The most common are: 

• From the application's startup code 

• Along with the other registration an application may do 

• From the application's setup program 

Tne Financial Server cails.RegPerfCounters while performing other registration tasks including registering COM 
components. Registration occurs when the Financial Server executable is started with the /RegServer command line 
argument. The following example demonstrates the use of the C++ utilities to perform registration in the Financial 
Server in an ATL-generated WinMain routine. 

extern "C" int WINAPI _tWinMain (HXNSTANCE hinstance, 

HINSTANCE /*hPrevIn3tance*/, LPTSTR IpCmdLine, int /♦nShowCmd*/) 

i 

tool bSuccess ° false; 

LPCTSTR IpszToken = FindOneOf (IpCmdLine, szTokens) ; 

while (IpszToken != NULL) 

( 

if (Istrcmpi (IpszToken, _T ( "RegServer") )°=0) 

Module. UpdateRegistryFromResource(IDR_FinancialServer, TRUE) ; 
"bSuccess « SUCCEEDED ( _Module .RegisterServer (TRUE) ) && 

RegisterPerformanceCounters("FinancialServer", CLSID_CFinServCounters) ; 

break; 

) 

if (Istrcmpi (IpszToken, _T ( "UnregServer") ) »«0) 
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{ 

^Module . UpdateRegistryFromResource { lDR_rinancialServer, FALSE) / 
bSuccess = SUCCEEDED(_Module.Unregi3terServer 0 ) && 
UnRegistorPerformanceCountoro ("FlnancialServer*') ; 
break; 

) 

IpszToken •» FindOneOf (IpszToken, szTokens); 

) 



_FigursLlJ5,___ 

Calling RegPerfmonCounters from Visual Basic 

As described above, registration Is done through a COM interface based on IDispatch (IReglsterPerfnrionObject). As a 
resuit, performance monitor counter registration can be done from any language that supports caiiing COM components. 
The following example shows Visual Basic code that registers counter Information during application startup. In Visual 
Basic, the type library from the RegPerfmonCounters DLL must be referenced in the project through the Project- 
>References dialog box before the registration component can be used. 

Private Sub Form_Load() 

Dim regPerfCounters As New RegisterPerfmonObject 

* Register the application's counters. The first parameter 

* is the application name and the second parameter is the 

* clsid of the component that implements iPerfmonObject 

regPerfCounters. Register "MyServer", "DA321ED6-79EA-11DO-8A16-400004491007" 
End Sub 

Figure 19. 

Step 4. Monitoring Your Application with PerfMon 

The final step in adding custom counters is to malce the ExtCounters DLL visible to Performance Monitor. 

Performance Monitor locates this by looking at the Library value In the application's Performance key. This information is 
added during the registration process. In order for Performance Monitor to find ExtCounters.dll it must be copied to a 
directory that is in the path, A common place to put ExtCounters.dll Is in the System32 folder under your NT directory. 

Now that the collection component has been implemented, registration has been done, and ExtCounters is visible to 
Performance Monitor, the application's custom counters are ready to use. The counters will appear in the "Add To Chart" 
dialog (see Rgure 8) in Performance Monitor and will show up on the charts when added. 

Other Performance Monitor Features 

Performance Monitor has several other features that a Performance DLL can support. These features include the support 
for multiple objects in an application, multiple instances per object, and various data and counter types. These features 
can be implemented generically in the ExtCounters DLL in the same way the features described In this paper have been. 

Conclusion 

Using Performance Monitor to tune and debug an application helps to produce a better quality application and to lower 
its TCO over time. An application takes advantage of Performance Monitor by supplying application-specific objects and 
counters that are displayed by Performance Monitor in the same way system provided objects are. Several steps and 
components are needed to implement custom counters using the native Performance Monitor interface. This paper 
describes a set of COM Interfaces, C++ classes and generic components that make the process of adding custom 
counters much easier. Because the Interface to Performance Monitor is described in terms of COM objects, the custom 
performance counters can be written in any language that supports the development of COM components. 
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